Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

Functions that return field values and attributes

The Query class that supports SDOs provides a large number of functions that you can use to retrieve data values and the properties of those fields.

column<attribute> functions

There is a whole set of functions that return individual 4GL attributes from fields in a data object (one for which the QueryObject property is TRUE, basically SDOs or SBOs).

These functions are located in an adjunct SDO super procedure called dataextcols.p. Both the query class and the data class have enough supporting functions that the code to support them causes compilation problems in older versions of the Progress 4GL. So the get and set functions for properties are in separate super procedures called queryext.p and dataext.p, respectively. In addition, the dataextcols.p procedure supports all these special column attribute functions. These are all run along with the standard super procedures query.p and data.p and made part of the super procedure stack.

These functions return values in the appropriate data type for the attribute. All the functions have names of column plus the attribute name. The prefix, column, is not entirely appropriate here, because these return field values from the current row in the SDO buffer, not browse column values.

They take a single input parameter, which is the name of the field. This can be:

A simple SDO field name.
A field name qualified by RowObject.
A field name qualified by the database table it is derived from.

Column attribute functions include:

columnColumnLabel — Returns the Column-Label of the field. Note the word column does appear twice in the function name.
columnDataType — Returns the data type of the underlying database field represented by this column.
columnDBColumn — Returns the name of the column in the database, in case it has been renamed in the SDO.
columnDBName — Returns the name of the database that the field is derived from.
columnHandle — Returns the handle of the field in the RowObject buffer.
columnHelp — Returns the value of the field’s Help text.
columnInitial — Returns the field’s initial value.
columnLabel — Returns the field’s label.
columnModified — Returns a LOGICAL flag indicating whether the field has been modified since it was read into the RowObject table.
columnPrivateData — Returns the Progress Private-Data attribute of a specified column.
columnTable — Returns the name of the database table the column is derived from. It is qualified according to how the SDO is defined.
columnWidth — Returns the width in characters.

There are also equivalent assignColumn<attribute> functions for most of these, which take the field name and the attribute value as input parameters.

There are also a few more specialized column functions that are useful.

columnQuerySelection

This CHARACTER function, supported for data objects, takes a column name as input and returns a CHR(1)-delimited string with all operators and values that have been added to the query for this field using the assignQuerySelection method (described later in this chapter). For example, if the query contains custnum > 5 and custnum < 9, this function returns >|5|<|9 (where CHR(1) is shown as |). Use this function to do analysis on the current query or to display information to the user.

columnValue

This CHARACTER function, supported for data objects, takes the name of the field as input and returns its value, in character form, but without any formatting characters added. This is equivalent to applying the STRING function to the BUFFER-VALUE of the field.

columnStringValue

This CHARACTER function, supported for data objects, takes the name of the field as input and returns its STRING-VALUE, which is the fully formatted value as it would appear on the screen (so it is the buffer equivalent to the SCREEN-VALUE of a displayed field or browse column).

colValues

This CHARACTER function, supported for data objects, takes as input a comma-separated list of field names in an SDO and returns a CHR(1)-delimited list of the formatted values (STRING-VALUEs, in effect) for those columns for the current row, preceded by a string called the RowIdent that holds the database RowID of the record the columns are derived from. If the SDO involves a join, then this first RowIdent entry in the list is itself a comma-separated list of the RowID values for the records in the join. This is the standard function used internally by viewers in particular to retrieve the values to display as the SCREEN-VALUEs of the fields in the viewer.

Note that because the RowIdent is always the first entry in the CHR(1)-delimited list, your code must always look for the value for a column that was in the nth position in the input list, in the n+1th position in the return value.

This function can be useful for retrieving multiple values at a time, but the columnValue and columnStringValue functions were designed for application use as a more convenient way to retrieve individual values at a time.

colStringValues

This CHARACTER function provides an alternative to colValues as a way to retrieve multiple values in a single call, and with flexible formatting. It does not return the RowIdent of the database records as colValues does. The function takes three INPUT parameters:

pcColumnList — This is a comma-delimited list of RowObject column names to return values for.
pcFormatOption — This parameter allows you to specify the format of returned values. It can be:
Blank or ? — No formatting is done; unformatted buffer values are returned.
Formatted — Returned values are formatted according to the columnFormat with right-justified numeric values.
TrimNumeric — Returned values are formatted according to the columnFormat with left-justified numeric values.
pcDelimiter — This optional parameter specifies a delimiter between values; the default delimiter is CHR(1).